home *** CD-ROM | disk | FTP | other *** search
/ PCGUIA 127 / PC Guia 127.iso / Software / Produtividade / OpenOffice.org 2.0.1 / openofficeorg4.cab / extend.txt < prev    next >
Text File  |  2005-11-19  |  4KB  |  84 lines
  1. Writing an IDLE extension
  2. =========================
  3.  
  4. An IDLE extension can define new key bindings and menu entries for IDLE
  5. edit windows.  There is a simple mechanism to load extensions when IDLE
  6. starts up and to attach them to each edit window. (It is also possible
  7. to make other changes to IDLE, but this must be done by editing the IDLE
  8. source code.)
  9.  
  10. The list of extensions loaded at startup time is configured by editing
  11. the file config-extensions.def.  See below for details.
  12.  
  13. An IDLE extension is defined by a class.  Methods of the class define
  14. actions that are invoked by event bindings or menu entries. Class (or
  15. instance) variables define the bindings and menu additions; these are
  16. automatically applied by IDLE when the extension is linked to an edit
  17. window.
  18.  
  19. An IDLE extension class is instantiated with a single argument,
  20. `editwin', an EditorWindow instance. The extension cannot assume much
  21. about this argument, but it is guarateed to have the following instance
  22. variables:
  23.  
  24.     text    a Text instance (a widget)
  25.     io        an IOBinding instance (more about this later)
  26.     flist    the FileList instance (shared by all edit windows)
  27.  
  28. (There are a few more, but they are rarely useful.)
  29.  
  30. The extension class must not directly bind Window Manager (e.g. X) events.
  31. Rather, it must define one or more virtual events, e.g. <<zoom-height>>, and
  32. corresponding methods, e.g. zoom_height_event().  The virtual events will be
  33. bound to the corresponding methods, and Window Manager events can then be bound
  34. to the virtual events. (This indirection is done so that the key bindings can
  35. easily be changed, and so that other sources of virtual events can exist, such
  36. as menu entries.)
  37.  
  38. An extension can define menu entries.  This is done with a class or instance
  39. variable named menudefs; it should be a list of pairs, where each pair is a
  40. menu name (lowercase) and a list of menu entries. Each menu entry is either
  41. None (to insert a separator entry) or a pair of strings (menu_label,
  42. virtual_event).  Here, menu_label is the label of the menu entry, and
  43. virtual_event is the virtual event to be generated when the entry is selected.
  44. An underscore in the menu label is removed; the character following the
  45. underscore is displayed underlined, to indicate the shortcut character (for
  46. Windows).
  47.  
  48. At the moment, extensions cannot define whole new menus; they must define
  49. entries in existing menus.  Some menus are not present on some windows; such
  50. entry definitions are then ignored, but key bindings are still applied.  (This
  51. should probably be refined in the future.)
  52.  
  53. Extensions are not required to define menu entries for all the events they
  54. implement. (XXX KBK 15Jul03: But it appears they must have keybindings for each
  55. virtual event?)
  56.  
  57. Here is a complete example example:
  58.  
  59. class ZoomHeight:
  60.  
  61.     menudefs = [
  62.         ('edit', [
  63.             None, # Separator
  64.             ('_Zoom Height', '<<zoom-height>>'),
  65.          ])
  66.     ]
  67.  
  68.     def __init__(self, editwin):
  69.         self.editwin = editwin
  70.  
  71.     def zoom_height_event(self, event):
  72.         "...Do what you want here..."
  73.  
  74. The final piece of the puzzle is the file "config-extensions.def", which is
  75. used to to configure the loading of extensions and to establish key (or, more
  76. generally, event) bindings to the virtual events defined in the extensions.
  77.  
  78. See the comments at the top of config-extensions.def for information.  It's
  79. currently necessary to manually modify that file to change IDLE's extension
  80. loading or extension key bindings.
  81.  
  82. For further information on binding refer to the Tkinter Resources web page at
  83. python.org and to the Tk Command "bind" man page.
  84.